<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Language" content="en-ca" />
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <meta name="description" content="Functions" />
        <link rel="stylesheet" type="text/css" href="../style.css" />
        <title>NAnt - Functions</title>
    </head>
    <body>
        <table width="100%" border="0" cellspacing="0" cellpadding="2" class="NavBar">
            <tr>
                <td class="NavBar-Cell">
                    <a title="NAnt home page" href="http://nant.sourceforge.net"><b>NAnt</b></a> <img src="../images/arrow.gif" alt="-&gt;" width="13" height="9" />
                    <a href="../index.html">Help</a> <img alt="-&gt;" src="../images/arrow.gif" /> <a href="index.html">
                        Fundamentals</a> <img height="9" alt="-&gt;" src="../images/arrow.gif" width="13" />
                    Functions
                </td>
                <td class="NavBar-Cell" align="right">
                    v0.91-alpha2
                </td>
            </tr>
        </table>
        <h1>Functions</h1>
        <p class="topicstatus">[This is preliminary documentation and subject to change.]</p>
        <p>NAnt provides a rich set of bulitin functions, that allow you to:</p>
        <ul>
            <li>
                manipulate strings</li>
            <li>
                manipulate date/time values</li>
            <li>
                manipulate path names</li>
            <li>
                read the properties of files/directories</li>
            <li>
                access current build information and more</li>
            <li>
                and more</li>
        </ul>
        <p>For a full list of supported functions, click <a href="../functions/index.html">here</a>.</p>
        <h3><a id="syntax" />Function Call Syntax</h3>
        <p>
            To call functions, use <code>prefix::function-name(argument1, ..., argumentN)</code>
            syntax within expressions. NAnt will (implicitly) try to convert the arguments 
            you pass to functions to correct types and will report an error in case of 
            failure.
        </p>
        <p>
            For example, assuming you would like to call <code>string::contains('0123456789',1)</code>
            which expects two <code>string</code> parameters, but you want to pass the 
            second parameter which is an integer. NAnt would attempt to convert the second 
            parameter from <code>int</code> to <code>string</code>, which succeeds and 
            function is called as if it was written as <code>string::contains('0123456789','1')</code>.
        </p>
        <p>The following table shows the possible type conversions:</p>
        <div class="table">
            <table>
                <tr>
                    <th>
                        From Type</th>
                    <th>
                        To Type</th>
                    <th>
                        Allowed</th>
                    <th>
                        Remarks</th>
                </tr>
                <tr>
                    <td><code>int</code></td>
                    <td><code>string</code></td>
                    <td>Yes</td>
                    <td>The conversion is always possible.</td>
                </tr>
                <tr>
                    <td><code>int</code></td>
                    <td><code>double</code></td>
                    <td>Yes</td>
                    <td>The conversion is always possible.</td>
                </tr>
                <tr>
                    <td><code>int</code></td>
                    <td><code>boolean</code></td>
                    <td>No</td>
                    <td>Can be done with the <code>if()</code> conditional operator or simply as <code>(value 
                            &lt;&gt; 0)</code></td>
                </tr>
                <tr>
                    <td><code>int</code></td>
                    <td><code>datetime</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>int</code> to <code>datetime</code>.</td>
                </tr>
                <tr>
                    <td><code>int</code></td>
                    <td><code>timespan</code></td>
                    <td>No</td>
                    <td>You can use the <code>timespan::from-xxx</code> functions to construct a <code>timespan</code> from a given number of days, months, ....</td>
                </tr>
                <tr>
                    <th colspan="4">
                    </th>
                </tr>
                <tr>
                    <td><code>string</code></td>
                    <td><code>int</code></td>
                    <td>Yes</td>
                    <td>If the string doesn't represent an integer value, an error is reported.</td>
                </tr>
                <tr>
                    <td><code>string</code></td>
                    <td><code>double</code></td>
                    <td>Yes</td>
                    <td>If the string doesn't represent a floating point value, an error is reported.</td>
                </tr>
                <tr>
                    <td><code>string</code></td>
                    <td><code>boolean</code></td>
                    <td>Yes</td>
                    <td>If the string isn't either <code>true</code> or <code>false</code> (case 
                        insensitive), an error is reported.</td>
                </tr>
                <tr>
                    <td><code>string</code></td>
                    <td><code>datetime</code></td>
                    <td>Yes</td>
                    <td>If the string doesn't represent a valid date/time, an error is reported. 
                        Date/time string format is <code>MM/DD/YYYY&nbsp;HH:MI:SS</code></td>
                </tr>
                <tr>
                    <td><code>string</code></td>
                    <td><code>timespan</code></td>
                    <td>No</td>
                    <td>
                        You can use <code>timespan::parse</code> to construct a <code>timespan</code> 
                        from a time indicated by a given string. If the string doesn't represent a valid 
                        timespan, an error is reported.
                    </td>
                </tr>
                <tr>
                    <th colspan="4">
                    </th>
                </tr>
                <tr>
                    <td><code>double</code></td>
                    <td><code>int</code></td>
                    <td>Yes</td>
                    <td>If the string doesn't represent an integer value, an error is reported.</td>
                </tr>
                <tr>
                    <td><code>double</code></td>
                    <td><code>string</code></td>
                    <td>Yes</td>
                    <td>The converted string uses dot as a fractional part separator so the result 
                        looks like <code>0.1234567</code></td>
                </tr>
                <tr>
                    <td><code>double</code></td>
                    <td><code>boolean</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>double</code> to <code>boolean</code>.</td>
                </tr>
                <tr>
                    <td><code>double</code></td>
                    <td><code>datetime</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>double</code> to <code>datetime</code>.</td>
                </tr>
                <tr>
                    <td><code>double</code></td>
                    <td><code>timespan</code></td>
                    <td>No</td>
                    <td>You can use the <code>timespan::from-xxx</code> functions to construct a <code>timespan</code> from a given number of days, months, ....</td>
                </tr>
                <tr>
                    <th colspan="4">
                    </th>
                </tr>
                <tr>
                    <td><code>boolean</code></td>
                    <td><code>int</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>boolean</code> to <code>int</code>. You may 
                        want to use <code>if(boolvalue,1,0)</code> instead.</td>
                </tr>
                <tr>
                    <td><code>boolean</code></td>
                    <td><code>string</code></td>
                    <td>Yes</td>
                    <td>The result is <code>'True'</code> or <code>'False'</code> string.</td>
                </tr>
                <tr>
                    <td><code>boolean</code></td>
                    <td><code>double</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>boolean</code> to <code>double</code>.</td>
                </tr>
                <tr>
                    <td><code>boolean</code></td>
                    <td><code>datetime</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>boolean</code> to <code>datetime</code>.</td>
                </tr>
                <tr>
                    <td><code>boolean</code></td>
                    <td><code>timespan</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>boolean</code> to <code>timespan</code>.</td>
                </tr>
                <tr>
                    <th colspan="4">
                    </th>
                </tr>
                <tr>
                    <td><code>datetime</code></td>
                    <td><code>int</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>datetime</code> to <code>int</code>.</td>
                </tr>
                <tr>
                    <td><code>datetime</code></td>
                    <td><code>string</code></td>
                    <td>Yes</td>
                    <td>The result is a datetime string with the following format: <code>MM/DD/YYYY&nbsp;HH:MI:SS</code></td>
                </tr>
                <tr>
                    <td><code>datetime</code></td>
                    <td><code>double</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>datetime</code> to <code>double</code>.</td>
                </tr>
                <tr>
                    <td><code>datetime</code></td>
                    <td><code>boolean</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>datetime</code> to <code>boolean</code>.</td>
                </tr>
                <tr>
                    <td><code>datetime</code></td>
                    <td><code>timespan</code></td>
                    <td>No</td>
                    <td>You can use the value of <code>datetime::get-ticks</code> to construct a <code>timespan</code> using <code>timespan::from-ticks</code>.</td>
                </tr>
                <tr>
                    <th colspan="4">
                    </th>
                </tr>
                <tr>
                    <td><code>timespan</code></td>
                    <td><code>int</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>timespan</code> to <code>int</code>.</td>
                </tr>
                <tr>
                    <td><code>timespan</code></td>
                    <td><code>double</code></td>
                    <td>No</td>
                    <td>You can use <code>timespan::get-ticks</code> to convert from <code>timespan</code> to <code>double</code>.</td>
                </tr>
                <tr>
                    <td><code>timespan</code></td>
                    <td><code>boolean</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>timespan</code> to <code>boolean</code>.</td>
                </tr>
                <tr>
                    <td><code>timespan</code></td>
                    <td><code>string</code></td>
                    <td>No</td>
                    <td>You can use <code>timespan::to-string</code> to obtain the string representation of a <code>timespan</code>.</td>
                </tr>
                <tr>
                    <td><code>timespan</code></td>
                    <td><code>datetime</code></td>
                    <td>No</td>
                    <td>You cannot convert from <code>timespan</code> to <code>datetime</code>.</td>
                </tr>
            </table>
        </div>
        <h3><a id="custom" />Custom Functions</h3>
        <p>
            Just as you can extend NAnt with your own tasks it is also possible to 
            implement your own functions for use in build files.</p>
        <p>Functions can be implemented in any .NET language and are loaded in the same 
            manner as tasks. ie either by locating your custom function assembly in the 
            NAnt bin directory or using the <code><a href="../tasks/loadtasks.html">&lt;loadtasks&gt;</a></code>
            task. Example C# code for a Hello World function :
        </p>
        <p>Define a custom function using C#.</p>
        <pre class="code">                    
[FunctionSet("hello", "Hello")]
public class HelloFunctions : FunctionSetBase {        
    public HelloFunctions(Project project, PropertyDictionary properties) : base(project, properties) {
    }
    [Function("hello-world")]
    public static string HelloWorldfunc() {
        return "Hello World!!";
    }
}
        </pre>
        <p>and call that function from a build file.</p>
        <pre class="code">       
&lt;echo message="${hello::hello-world()}" /&gt;
        </pre>
        <p>A quick and easy way to develop new functions is to use the <code><a href="../tasks/script.html">
                &lt;script&gt;</a></code> task. This allows you to create and test new functions 
            without the overhead of building an external assembly. The <code><a href="../tasks/script.html">
                &lt;script&gt;</a></code> task documentation contains examples of custom function 
            definitions.</p>
    </body>
</html>
